Security

SSH Access

Structr includes a built-in SSH server that provides command-line access to the Admin Console and filesystem. Administrators can connect via SSH to execute scripts, run queries, and manage files without using the web interface.

Overview

The SSH service provides two main capabilities:

• Admin Console - An interactive command-line interface for executing JavaScript, StructrScript, Cypher queries, and administrative commands
• Filesystem Access - SFTP and SSHFS access to Structr’s virtual filesystem

Any user with a configured key can log in. The Admin Console, however, requires backend access, which only admin users have: a non-admin user who opens a shell or runs a console command is refused with “Access denied. User has no backend access.” or “Access denied. Console commands require backend (admin) access.”, while SFTP and scp remain available to them, subject to the permissions on the individual files and folders.

Enabling the SSH Service

The SSH service is not enabled by default. To activate it:

1. Open the Configuration Interface
2. Enable the SSHService in the list of configured services
3. Save the configuration
4. Navigate to the Services tab
5. Start the SSHService

When the service starts successfully, you see log entries like:

INFO  org.structr.files.ssh.SSHService - Setting up SSH server..
INFO  org.structr.files.ssh.SSHService - Initializing host key generator..
INFO  org.structr.files.ssh.SSHService - Configuring SSH server..
INFO  org.structr.files.ssh.SSHService - Starting SSH server on port 8022
INFO  org.structr.files.ssh.SSHService - Initialization complete.

On first startup, Structr generates an SSH host key and stores it locally. This key identifies your Structr instance to SSH clients.

Configuration

Configure the SSH service in structr.conf:

Remember that structr.conf only contains settings that differ from defaults. If you want to use port 8022, you do not need to add this setting.

Setting Up User Access

By default, SSH authentication uses public key authentication. Each user who needs SSH access must have their public key configured in Structr. The user’s publicKey property holds a single key, and the publicKeys property holds an array of further keys; a login succeeds if the presented key matches any of them.

To add a public key for a user:

1. Open the Security area in the Admin UI
2. Select the user
3. Open the Edit dialog
4. Navigate to the Advanced tab
5. Paste the user’s public key into the publicKey field
6. Save the changes

The public key is typically found in ~/.ssh/id_rsa.pub or ~/.ssh/id_ed25519.pub on the user’s machine. The entire contents of this file should be pasted into the field.

Structr also supports password authentication with the user’s Structr password, but rejects it while application.ssh.forcepublickey is set (the default), logging “Password-based SSH connections are forbidden”. Set it to false only if you cannot distribute keys, since the password then travels with every login.

Note: Every user can log in, but only users with isAdmin = true have backend access and can use the Admin Console. Non-admin users are limited to SFTP and scp.

Connecting via SSH

Connect to Structr using a standard SSH client:

ssh -p 8022 admin@localhost

Replace admin with your username, localhost with your server address, and 8022 with your configured port.

On first connection, you are prompted to verify the server’s host key fingerprint:

The authenticity of host '[localhost]:8022 ([127.0.0.1]:8022)' can't be established.
RSA key fingerprint is SHA256:9YVTKL8x/PUhOdQUPdDmwdCDqZmDzbE5NuXlY16jQeI.
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

After confirming, you see the welcome message and enter the Admin Console:

Welcome to the Structr 6.2-SNAPSHOT JavaScript console. Use <Shift>+<Tab> to switch modes.
admin@Structr/>

Admin Console

The Admin Console provides an interactive environment for executing commands. It supports multiple modes, each with different capabilities.

Switching Modes

Use Console.setMode() to switch between modes:

Console.setMode('JavaScript')   // Default mode
Console.setMode('StructrScript')
Console.setMode('Cypher')
Console.setMode('AdminShell')

You can also press Shift+Tab to cycle through available modes.

JavaScript Mode

The default mode. Execute JavaScript code with full access to Structr’s scripting API:

admin@Structr/> $.find('User')
admin@Structr/> $.find('Project', { status: 'active' })
admin@Structr/> $.create('Task', { name: 'New Task' })

StructrScript Mode

Execute StructrScript expressions:

admin@Structr/> find('User')
admin@Structr/> size(find('Project'))

Cypher Mode

Execute Neo4j Cypher queries directly:

admin@Structr/> MATCH (n:User) RETURN n
admin@Structr/> MATCH (p:Project)-[:HAS_TASK]->(t:Task) RETURN p.name, count(t)

AdminShell Mode

Access administrative commands. Type help to see available commands:

admin@Structr/> Console.setMode('AdminShell')
Mode set to 'AdminShell'. Type 'help' to get a list of commands.
admin@Structr/> help

Filesystem Access

You can mount Structr’s virtual filesystem on your local machine using SSHFS. This allows you to browse and edit files using standard file management tools.

Mounting with SSHFS

Install SSHFS on your system if not already available, then mount the filesystem:

sshfs admin@localhost:/ mountpoint -p 8022

Replace:

• admin with your username
• localhost with your server address
• mountpoint with your local mount directory
• 8022 with your configured SSH port

After mounting, you can navigate the Structr filesystem like any local directory:

cd mountpoint
ls -la

Unmounting

To unmount the filesystem:

fusermount -u mountpoint   # Linux
umount mountpoint          # macOS

Troubleshooting

Connection Refused

If you cannot connect:

• Verify the SSHService is running in the Services tab
• Check that the port is not blocked by a firewall
• Confirm you are using the correct port (default: 8022)

# Check if the port is listening
netstat -tlnp | grep 8022

Authentication Failures

If authentication fails:

• Verify the public key is correctly entered in the user’s publicKey or publicKeys field
• If you log in with a password, check that application.ssh.forcepublickey is set to false
• Check that you are using the matching private key on the client

# Test with verbose output to see authentication details
ssh -v -p 8022 admin@localhost

“Access denied. User has no backend access.”

This error, or “Access denied. Console commands require backend (admin) access.” when running a single command, indicates that the user authenticated successfully but does not have admin privileges. The user can still use SFTP and scp. Set isAdmin = true on the user to grant access to the Admin Console.

Security Considerations

SSH access provides powerful administrative capabilities. Consider these security practices:

• Limit admin users - Only grant admin status to users who genuinely need it
• Protect private keys - Users should secure their private keys with passphrases
• Use strong keys - Prefer Ed25519 or RSA keys with at least 4096 bits
• Monitor access - Review server logs for SSH connection attempts
• Firewall the port - Restrict SSH port access to trusted networks if possible

Related Topics

• User Management - Managing users and the publicKey property
• Configuration - Service configuration in structr.conf
• Admin Console - Detailed documentation of console commands and modes